è Ë }™8}}√}} }} €≠~wx E é€≠ &u â€≠ +s Ò€≠ %u ã€≠ (• ã€≠ %x
€≠ %™ "ì€≠ &w (ü€≠}|‘ Ï @ } R ≠ ‰ √ É ı ≠ ç ¿ è ¿ é ¿ É ∂ Å Ç Å ç Å É ù É Q … f À f Ú f Û f ñ f f f 9 f X f Y Ü t Ü v Ü ∫ Ü “ Ü Ë Ü Í Ü Î f Ï f â f ä f û f f f = f R f U f ¡ f Ô f Õ f
Ø Ø _ Ø a Ø ı Ø ƒ Ø ì Ø î Ø fl Ø É ¨ ≈ Ô à à $ à & à 3 à X à o à q à — à ˘ à ˝ à Ê à à à ö à ù à ÿ à à ' à ) Ã * Q É û " Ø Ø Ø H Ø | Ø ~ Ã ¿ ˙ É
Å Å 9 Å ^ Å z ⁄ É ñ ∫ Ê E Ê z Ê ¯ É _ { É c ∫ — Ê » É !/ Ê !C É !« Ê !á Ê !ø É "e à "g "∞ É "ì ∫ #  #:  #I  #d  #p #Ÿ É $º É $» Ê $Ø Ê $ó Ê % Ê %( Ê %3 Ê %I Ê %h Ê %s Ê %≈ Ê %¨ Ê %“ Ê %Î Ê %† Å %fi ¿ %ò É (Z É (œ ∫ († Ê (ü Ê ) Ê )
É )Ë É *i ∫ *« Ø *Ë Ø *â Ø + Ø +" é +* ë ++ ö +p ö +º ö , ö ,, ö ,- ö ,? ö ,@ ö ,º ö ,» ö -Ÿ -⁄ o -ı É ≥ k à ; à ` Q
Some Techniques for Handling Variables in Apple Guide
By Don Swatman
don@bilpin.co.uk
Developer Technical Support (DTS)
Apple Guide has many advantages over other help systems but also has several drawbacks. One is that it is not easy to keep track of what the user has already done. This becomes a particular problem if you are writing a tutorial. For example, your tutorial might have 10 different lessons which the user may need to complete over several days. How can the user be sure that he or she has gone back to the point they left the tutorial and not skipped stages? One way to do this is to store variables within an application.
This Technote also discusse Çs using helper applications with Apple Guide.
Storing Apple Guide Variables in an Application
Storing the variables within your application is often the easiest place to put them. You need to do several things:
¥ Create storage for the variables and initialize them
¥ Install Apple Event handlers
¥ Install custom context check handlers
The examples below just store an array of longs and initialize everything to 0 each time the application is run. For simplicity sake, the codes only going to set them to 0 or 1 and test whether they are 0 or non 0. An unregistered suite of Apple Events 'Vals' is going to be used. This is for demonstration purposes only and you should use your own ID's. The Apple Guide accesses variables 1 to 3, however, as arrays in 'C' start from 0, indexes from the guide are mapped from 1-3 to 0-2.
Installing and Initializing
You need to create storage for variables and then initialize them. You may want to store and recall these f flrom a preference file or clear them each time the application is run. Listing 1 contains storage for 3 variables and a context check reference. It also shows how to initializes them and install the handlers.
Listing 1. Initializing the guide variables and handlers
// Maximum number of values that can be stored by app
#define kMaxAGEntries 3
// Storage for values
long gAGValues[kMaxAGEntries];
// Storage for context check references
AGContextRefNum contextRefNum;
void ClearAllAGValues()
{
long count;
for (count=0;count < kMaxAGEntries;count++)
gAGValues[count] = 0;
}
OSErr InitAGVars()
{
OSErr theErr = noErr;
short count;
// Clear all the values stored by the application
ClearAllAGValues();
// Install context check handler. MyContextCallBack will get called when a
// context check of 'Vals' is queried by the Guide
pascal OSErr SetAGValues1(const AppleEvent *message, const AppleEvent *reply, long refcon)
{
gAGValues[0] = 1;
return( noErr );
}
pascal OSErr ClearAGValues1(const AppleEvent *message, const AppleEvent *reply, long refcon)
{
gAGValues[0] = 0;
return( noErr );
}
For ease, you may want to clear all the variables. This is done by event ID 'Cler'.
Listing 3. Clearing all the variables
pascal OSErr ClearAGValues(const AppleEvent *message, const AppleEvent *reply, long refcon)
{
ClearAllAGValues();
return( noErr );
}
Interrogating Variables
Checking the state of the variables is handled by Apple Guide context checks. There are mechanisms to pass data from a guide file into a context check; therefore, you only need one check which can be used to interrogate all the values. In this case, two longs are passed in the pInputData parameter. The easiest way to access them is to create a structure.
If command contains a 0, then a check is made to see if the value is 0. If it contains a 1, then the check sees it if the value is non-0. Index is used to define which variable to check.
Listing 4. Context check
pascal OSErr MyContextCallBack( Ptr pInputData,
Size inputDataSize,
Ptr *ppOutputData,
Size *pOutputDataSize,
AGAppInfoHdl hAppInfo )
{
OSErr theErr = noErr;
Boolean checkResult = false;
// Check the index is within range
if (((P ÿassedAGParamPtr)pInputData)->index <= kMaxAGEntries)
// Work out whether we need to return true or false
Once the result of the check has been determined, MySetContextResult() is used to fill in the ppOutputData and pOutputDataSize. The result is returned in this way because it is part of a far wider mechanism. MySetContextResult creates a pointer and moves the value in result into to it É. Next, it returns the newly created pointer and the size of the data within it. Apple Guide is responsible for deallocating this pointer.
Before your application quits, you should remove the context check handlers using AGRemoveContextHandler. You also may want to save the variables into a preference file.
ClearValues sends the Apple Event 'Cler' of event class 'Vals' to the application with the creator type 'AgHp'. This is defined in the application to clear all variables to 0.
Defining the Context Checks
As previously mentioned, context checks have a mechanism for passing data. They are defined in the additional parameters of the <DCC> command. In this case, if we want to check that a variable has been set,we would use the command:
Listing 8. Defining the context checks.
<DCC> "IsFlagSet", 'V ìals', 'AgHp', LONG:1, LONG
'Vals' is the context check in the application with the identifier 'AgHp'. The first additional parameter is a long with a default value of one. The second is a long which will need a value entered each time the check is used. These two parameters correspond to the data structure PassedAGParamType described above, therefore to check to see if variable one has been set:
<If> (IsFlagSet(1))
If you want to be more specific, for example a check to see if lesson one has been completed could be:
Note that because both parameters have defaults, you don't need to enter a parameter when the check is used.
Marking Sequences Completed
To mark a sequence completed, use an <On Panel Hide> command with a suitable event to set the variable.
Listing 9. Marking a sequence complete
<Define Panel> "Lesson 1 - last panel"
Panel text....
<On Panel Hide> SetFlag1()
<End Panel>
Skipping Completed Sequences ˇ
To skip sequences, create a containing sequence that will take you through your tutorial. You'll probably want to put an intro and outro panel into the sequence. To decide whether to show a lesson sequence, use the <If> command as shown below. This will skip lessons that have already been completed.
<Define Sequence> "Tutorial"
<Panel> "Tutorial Intro"
<If> NOT Flag1Set()
<Jump Sequence> "Lesson 1"
<End If>
<If> NOT Flag2Set()
<Jump Sequence> "Lesson 2"
<End If>
<If> NOT Flag3Set()
<Jump Sequence> "Lesson 3"
<End If>
<Panel> "Tutorial Outro"
<End Sequence>
Helper Applications
It's not always possible for a guide author to have acc Ñess to the applications source, therefore it is not always possible to add the features described above to an application. Also, some applications use Apple Events but are not necessarily scripted. Setting up these events may be very difficult or impossible from Apple Guide. In these cases, it's possible to write a small background only application which can be used to store variables and from simple Apple Eventsm create and trigger far more sophisticated events. This small application could be used to store variables and handle the code described above.
To trigger it, you need to add a compiled Apple Script to the application.
Listing 10. Apple Script to trigger helper application
tell application "AGHelperApp"
launch
end tell
When you compile the script, make sure the helper application is in the same folder as the script. Also, if you change the creator type of the helper, you will need to recompile the script.
You will probably need to start the helper from Ë the first panel of the tutorial sequence. In the example below, the compiled script is called StartHelperApp.
Listing 11. Starting the helper application from within the guide
Guide files and tutorials can seriously add to the usability of your
product. Keeping track of how far the user has gone through your tutorial
will help the user learn your product. The techniques in this Technote will
help you to implement this. Use them!
Further Reference
¥ Apple Guide Complete, published by Addison-Wesley, is an essential volume if you are writing Apple Guide help systems.
¥ AGVariable sample code is an example implementation using the techniques described in this Technote. It contains a 'C' file that can be added to your application however it based around a helper application.
Acknowledgments
Special thanks to Jason Hodges-Harris. Z ÿÿ N € Ò DSET ≠ ÿÿ . H H ÿÿÿÿÿÿ}}¬ € ° b ¯ 0 € ÿÿ 6 ÿÿ * b ¯ DSET Δ ÿÿ . H §/.ÿÿÿÿÿÿ}}ô ¯ ≠ € ÿÿ ° 2 € ÿÿ ` â € ÿÿ
‚ € ÿÿ
À
B € ÿÿ
p ò € ÿÿ ¢ € ÿÿ ‹ R € ÿÿ • € ÿÿ ∞ ° € ÿÿ 3 ` € ÿÿ ã € ÿÿ
„
À € ÿÿ
C
p € ÿÿ ó € ÿÿ £ ‹ € ÿÿ S • € ÿÿ 0 € ÿÿ 6 ÿÿ * b ¯ DSET ≠ ÿÿ . H -ü < \ÿÿÿÿÿÿ}™T ?• I - € ÿÿ °
ÿÿ * ?• I € - › € -
Ü € - † € - † € -
† € - † € - † € - 6 € - † DSET T @ } {€Ü}~À}™(}z € -}{≥ , i i i } i $ " à m " à p " à m r [ˇP[¥ΔWWl≤[¡‰
ÿÿÿÿ 6 ?0 6 8 # ÿÿÿÿ 7 @0 6 8 # ÿÿÿÿ 8 A0 6 7 $ ÿÿÿÿ 9 B0 6 7 $ ÿÿÿÿ : C0 6 9 " ÿÿÿÿ ; D0 6 9 # ÿÿÿÿ % < E‹ ÿÿÿÿ ÿÿ = F0 E E % ÿÿÿÿ > G0 E E ÿÿÿÿ ? H0 E E ÿÿÿÿ @ I0 E G & ÿÿÿÿ A K0 E G ÿÿÿÿ B L0 E G ÿÿÿÿ C M0 E G ! ÿÿÿÿ D N0 E G " ÿÿÿÿ E O0 E G # ÿÿÿÿ F P0 E F ' $
ÿÿÿÿ G Q0 E F ' %
ÿÿÿÿ H R0 E H & ÿÿÿÿ I S0 E H ' ÿÿÿÿ % J T‹ ÿÿÿÿ ( ÿÿ K U0 T T ( ) ÿÿÿÿ L V0 T T * ÿÿÿÿ M W0 T T + ÿÿÿÿ N X0 T V , ÿÿÿÿ O Y0 T V - ÿÿÿÿ P Z0 T V . ÿÿÿÿ Q [0 T V / ÿÿÿÿ R \0 T V 0 ÿÿÿÿ S ]0 T V 1 ÿÿÿÿ T ^0 T U ) 6
RULR}™P ÿÿÿ ÿ ÿÿ / ÿ ÿÿ ‡ @ ÿÿ \ ÿÿ Â B d ÿÿ ÿ ˚ÿô N N .
⁄
° =
H ø Ç.R ˘\æ * ™ Ç≥P Ç „6f „1Ì Ç.R „1N Ç0Ü Çÿÿ b B ÿÿ $ ÿÿ ÿ @ ÿÿ ÿÿ @ ÿÿ $ ÿÿ H ÿÿ ÿ ª B < ÿÿ íÿ Zÿô N N .
⁄
° =
H ø Ç.R ˘\æ * ™ Ç≥P Ç „6f „1Ì Ç.R „1N Ç0Ü Çÿÿ l ÿÿ ÿ b B ÿÿ Δ ÿÿ ´ ÿÿ iÿ  B d ÿÿ Ø ÿÿ ífl Zÿô N N .
⁄
° =
H ø Ç.R ˘\æ * ™ Ç≥P Ç „6f „1Ì Ç.R „1N Ç0Ü Çÿÿ iÿ b B ÿÿ ü ÿÿ ifl R 6 ÿÿ ÿÿ D ÿÿ h ÿÿ
‘ ÿÿ ÿ rÿô N N .
⁄
° =
H ø Ç.R ˘\æ * ™ Ç≥P Ç „6f „1Ì Ç.R „1N Ç0Ü Çÿÿ iÿ b B ÿÿ iÿ ª B < ÿÿ aÿ ˚ ÿÿ íÿ bÿô N N .
⁄
° =
H ø Ç.R ˘\æ * ™ Ç≥P Ç „6f „1Ì Ç.R „1N Ç0Ü Ç >ÿÿÿÿ ifl j B ÿÿ iö Z D ÿÿ i÷ Z E ÿÿ ° ÿÿ ÿÿ $ ÿÿ H ÿÿ l ÿÿ Δ ÿÿ ´ ÿÿ Ø ÿÿ ü ÿÿ ÿÿ D ÿÿ h ÿÿ ÿÿ $ ÿÿ H ÿÿ l ÿÿ Δ ÿÿ ´ ÿÿ ÿ  B d ÿÿ ÿ b B ÿÿ iÿ Z 6 ÿÿ ÿ Z 6 ÿÿ ÿ Zÿô N N .
⁄
° =
H ø Ç.R ˘\æ * ™ Ç≥P Ç „6f „1Ì Ç.R „1N Ç0Ü Çÿÿ iö R D ÿÿ ÿ ˚ Cÿÿÿÿ ÿ j B ÿÿ i÷ R D ÿÿ ÿ bÿô N N .
⁄
° =
H ø Ç.R ˘\æ * ™ Ç≥P Ç „6f „1Ì Ç.R „1N Ç0Ü Çÿÿ i÷ Z D ÿÿ íÿ ˚ÿô N N .
⁄
° =
H ø Ç.R ˘\æ * ™ Ç≥P Ç „6f „1Ì Ç.R „1N Ç0Ü Ç Mÿÿÿÿ iÿ … B ÿÿ íÿ rÿô N N .
⁄
° =
H ø Ç.R ˘\æ * ™ Ç≥P Ç „6f „1Ì Ç.R „1N Ç0Ü Çÿÿ i÷ Z C ÿÿ iö R C ÿÿ ÿ Z E ÿÿ ÿ Z D ÿÿ ÿ Z C ÿÿ afl ˚ ÿÿ ÷ C ÿÿ ÿ C ÿÿÿÿÿÿ ÿ … B ÿÿ ÿ C Ò Kÿÿ HASH ÿ Cÿ L K÷ K Kÿ N ‚ : ƒ I H ¡ G œ œ î>
ó û 9 ‡ J ø Fø <ù ?ù E ø # ù A
ù $ W> ÿ 1, 2Q 3v 4˝ 5À 6 ˛
=œ 8‡
, Q v ˝ À å &
/ T y ı Ã %, 'Q (v )˝ *À +å ,
- / . T / y 0
0 @
@ ÿ @‡ e e 7eo n&͆ ;n.͆ @n>͆ nf͆ oÍÜ o͆ o͆ !o+͆ DoS͆ B ù LKUP ı
Default SS Header Body Footer Footnote Footnote Index
HeadingH2.H2 Code.CV
Heading1.H1 Italic HeadingH3.H3 Title Author Number Classic % Blue Gray 1 6 Blue Gray 2 EColorful T
3D Table 1 ‘
3D Table 2 ˜
Accounting Harvard –Legal ¸Diamond gBullet+ aAddress h Affiliation d Bullet items u Further Ref vAcknowledgments ~Footer xFurther Reference T ÿÿ " APPSBullet ´ Checklist ´ Δ D FNTM Helvetica Geneva Palatino Monaco Courier Chicago
